"""
MicroPython machine module stubs
Provides access to hardware-specific functions
"""

from typing import Optional, Union, Callable, List, Tuple

# Constants
IDLE: int
SLEEP: int
DEEPSLEEP: int

class Pin:
    """Control I/O pins"""

    # Pin modes
    IN: int
    OUT: int
    OPEN_DRAIN: int

    # Pull modes
    PULL_UP: int
    PULL_DOWN: int

    # IRQ triggers
    IRQ_FALLING: int
    IRQ_RISING: int
    IRQ_LOW_LEVEL: int
    IRQ_HIGH_LEVEL: int

    def __init__(self, id: Union[int, str], mode: int = -1, pull: int = -1, value: Optional[int] = None) -> None:
        """
        Create a Pin object

        Args:
            id: Pin identifier (number or name)
            mode: Pin mode (IN, OUT, OPEN_DRAIN)
            pull: Pull mode (PULL_UP, PULL_DOWN, or None)
            value: Initial value (0 or 1)
        """
        ...

    def value(self, x: Optional[int] = None) -> Optional[int]:
        """Get or set the pin value (0 or 1)"""
        ...

    def on(self) -> None:
        """Set pin to high (1)"""
        ...

    def off(self) -> None:
        """Set pin to low (0)"""
        ...

    def irq(self, handler: Optional[Callable] = None, trigger: int = IRQ_FALLING | IRQ_RISING) -> Callable:
        """Configure an interrupt handler"""
        ...

class PWM:
    """Pulse Width Modulation"""

    def __init__(self, dest: Pin, freq: int = 1000, duty: int = 512) -> None:
        """
        Create a PWM object

        Args:
            dest: Pin object to use for PWM
            freq: Frequency in Hz
            duty: Duty cycle (0-1023)
        """
        ...

    def freq(self, value: Optional[int] = None) -> Optional[int]:
        """Get or set PWM frequency"""
        ...

    def duty(self, value: Optional[int] = None) -> Optional[int]:
        """Get or set PWM duty cycle (0-1023)"""
        ...

    def duty_u16(self, value: Optional[int] = None) -> Optional[int]:
        """Get or set PWM duty cycle (0-65535)"""
        ...

    def deinit(self) -> None:
        """Disable PWM"""
        ...

class ADC:
    """Analog to Digital Converter"""

    # Attenuation levels
    ATTN_0DB: int
    ATTN_2_5DB: int
    ATTN_6DB: int
    ATTN_11DB: int

    # Width
    WIDTH_9BIT: int
    WIDTH_10BIT: int
    WIDTH_11BIT: int
    WIDTH_12BIT: int

    def __init__(self, pin: Union[Pin, int]) -> None:
        """Create an ADC object"""
        ...

    def read(self) -> int:
        """Read ADC value (0-4095 for 12-bit)"""
        ...

    def read_u16(self) -> int:
        """Read ADC value as 16-bit (0-65535)"""
        ...

    def atten(self, value: int) -> None:
        """Set attenuation level"""
        ...

    def width(self, value: int) -> None:
        """Set resolution width"""
        ...

class UART:
    """Universal Asynchronous Receiver/Transmitter"""

    def __init__(self, id: int, baudrate: int = 9600, bits: int = 8, parity: Optional[int] = None, stop: int = 1, **kwargs) -> None:
        """Create a UART object"""
        ...

    def read(self, nbytes: Optional[int] = None) -> Optional[bytes]:
        """Read bytes"""
        ...

    def readline(self) -> Optional[bytes]:
        """Read a line"""
        ...

    def write(self, buf: Union[bytes, str]) -> Optional[int]:
        """Write bytes"""
        ...

    def any(self) -> int:
        """Return number of bytes waiting"""
        ...

class I2C:
    """Inter-Integrated Circuit bus protocol"""

    def __init__(self, id: int = -1, scl: Optional[Pin] = None, sda: Optional[Pin] = None, freq: int = 400000) -> None:
        """Create an I2C object"""
        ...

    def scan(self) -> List[int]:
        """Scan for I2C devices"""
        ...

    def readfrom(self, addr: int, nbytes: int) -> bytes:
        """Read from device"""
        ...

    def writeto(self, addr: int, buf: bytes) -> int:
        """Write to device"""
        ...

class SPI:
    """Serial Peripheral Interface bus protocol"""

    def __init__(self, id: int, baudrate: int = 1000000, polarity: int = 0, phase: int = 0, bits: int = 8, sck: Optional[Pin] = None, mosi: Optional[Pin] = None, miso: Optional[Pin] = None) -> None:
        """Create an SPI object"""
        ...

    def read(self, nbytes: int, write: int = 0x00) -> bytes:
        """Read bytes"""
        ...

    def write(self, buf: bytes) -> Optional[int]:
        """Write bytes"""
        ...

    def write_readinto(self, write_buf: bytes, read_buf: bytes) -> None:
        """Write and read simultaneously"""
        ...

class Timer:
    """Hardware timer"""

    ONE_SHOT: int
    PERIODIC: int

    def __init__(self, id: int = -1) -> None:
        """Create a Timer object"""
        ...

    def init(self, mode: int = PERIODIC, period: int = -1, callback: Optional[Callable] = None) -> None:
        """Initialize the timer"""
        ...

    def deinit(self) -> None:
        """Deinitialize the timer"""
        ...

class RTC:
    """Real Time Clock"""

    def __init__(self) -> None:
        """Create an RTC object"""
        ...

    def datetime(self, datetimetuple: Optional[Tuple] = None) -> Tuple:
        """Get or set date and time"""
        ...

class WDT:
    """Watchdog Timer"""

    def __init__(self, timeout: int = 5000) -> None:
        """Create a WDT object with timeout in milliseconds"""
        ...

    def feed(self) -> None:
        """Feed the watchdog"""
        ...

def reset() -> None:
    """Reset the device"""
    ...

def soft_reset() -> None:
    """Soft reset the device"""
    ...

def reset_cause() -> int:
    """Get the reset cause"""
    ...

def unique_id() -> bytes:
    """Get unique device ID"""
    ...

def freq(hz: Optional[int] = None) -> Union[int, Tuple]:
    """Get or set CPU frequency"""
    ...

def idle() -> None:
    """Enter idle mode"""
    ...

def sleep() -> None:
    """Enter sleep mode"""
    ...

def deepsleep(time_ms: Optional[int] = None) -> None:
    """Enter deep sleep mode"""
    ...

def time_pulse_us(pin: Pin, pulse_level: int, timeout_us: int = 1000000) -> int:
    """Time a pulse on a pin"""
    ...
